Status

Ready for API/design review at exact head 5b0802a6823eba6372cd11361dd4c37b87f2cac2. The branch is rebased onto current WGPU main, is conflict-free, and every required check is green. Codecov now reports all modified and coverable lines covered.

This PR is intentionally stacked on #268. Please merge #268 first. After #268 is rebased and merged, I will do one final rebase that removes its four Android-owned commits from this branch and leaves only the typed-surface follow-up.

One canonical dependency packaging step also remains before merge: go-webgpu/webgpu#24 is merged at a801aed7399042e5564ef76fc9f075da5cb70081, but no release contains it yet. CI therefore tests that exact clean canonical source through a temporary workspace. The final rebase should consume the first canonical WebGPU release containing #24; no fork, committed replace, or committed go.work is needed.

Why

#268 proves the pure-Go Android Vulkan mechanism, but its compatibility entry point still carries two untyped uintptr values. This follow-up maps the public/core/HAL surface seam to Rust wgpu v29.0.3 (4cbe6232b2d7c289b6e1a38416a6ae1461a22e81), following the exact-parity review direction established in #253.

Thanks @kolkov for pushing both that parity direction and the minimal host boundary on #268. This implementation follows both: WGPU owns surface creation from a caller-supplied native handle downward; Activity, JNI, packaging, and nativeexport stay in the host.

We are very excited to get this upstream cleanly because our game engine needs Android support, and we are happy to handle the remaining rebase, dependency release update, testing, and review follow-ups. Nothing in this API is engine-specific.

What this adds

• SurfaceTarget for a safe provider sampled once and retained until backend surface teardown;
• opaque SurfaceTargetUnsafe constructors for Win32, Xlib, Wayland, Android NDK, Metal, and Web targets;
• CreateSurfaceFromTarget and CreateSurfaceUnsafe, while preserving the existing CreateSurface as a compatibility adapter;
• a typed hal.SurfaceTarget discriminator so backends reject foreign handle kinds before pointer use;
• Rust-shaped per-backend surface ownership, compatible-adapter qualification, configuration, and release ordering;
• the same public contract across the pure-Go, rust, and browser implementations; and
• deterministic tests for provider retention, per-backend mapping, lazy backend creation, adapter compatibility, release cleanup, legacy mapping, and error paths.

The exhaustive exported-symbol and ownership map is in docs/SURFACE-TARGETS.md.

Dependency and merge order

Already merged:

• wgpu#264, drain before device teardown;
• wgpu#265, fail-closed swapchain negotiation;
• wgpu#266, explicit mock construction;
• wgpu#267, surface-qualified present queue;
• wgpu#269, surface lifetime ownership;
• goffi#62, released as canonical goffi v0.6.1; and
• webgpu#24, canonical Android Rust-wrapper surface source, merged as a801aed7399042e5564ef76fc9f075da5cb70081.

Remaining sequence:

1. publish a canonical go-webgpu/webgpu release containing Intel Vulkan Driver Bug: vkCreateGraphicsPipelines Returns VK_SUCCESS with VK_NULL_HANDLE #24;
2. rebase and merge docs(android): reconcile preview integration after #273 #268 onto current WGPU main;
3. rebase this PR onto merged docs(android): reconcile preview integration after #273 #268, bump to that canonical WebGPU release, rerun CI, then merge feat(surface): match Rust v29 typed surface targets #273.

Keeping these concerns separate preserves review history and leaves every merge intermediate cgo-free.

Android 29-36 contract

• API 29 is the native symbol and application install floor.
• API 29 uses the Rust-matching infinite acquire timeout; API 30 through API 36 share the bounded one-second path and have explicit policy coverage.
• API 36 is the downstream Java compile/Play target and newest runtime-observer endpoint, not a separate WGPU ABI.
• NDK r29 publishes native wrappers only through API 35, so native CI correctly compiles at the API 29 floor rather than claiming a nonexistent API 36 clang target.
• The caller owns the ANativeWindow reference through surface release; WGPU neither acquires/releases it nor owns Activity lifecycle.

Validation

CI run 30037307352 is fully green at the exact head above:

• build and test on Linux, macOS, and Windows;
• lint, formatting, dependency, and GLES/EGL integration checks;
• Android arm64 preview on Go 1.25.12 and Go 1.26.5; and
• Codecov patch coverage: all modified and coverable lines covered.

The Android gate uses NDK r29, compiles every package/test and the headless example through both default and rust implementations with CGO_ENABLED=0 and CGO_ENABLED=1, checks Go/NDK ABI layouts, and audits ELF dependencies. It pins canonical goffi v0.6.1 and the exact clean webgpu#24 merge above.

Additional focused local checks passed:

GOTOOLCHAIN=go1.25.12 CGO_ENABLED=0 GOWORK=off go test -count=1 ./core . ./hal/vulkan
CGO_ENABLED=0 GOWORK=off go vet ./core . ./hal/vulkan
CGO_ENABLED=0 GOWORK=off go test -count=1 $(CGO_ENABLED=0 GOWORK=off go list ./... | grep -v '/hal/metal$')

Cross-build and policy proof do not substitute for representative physical-device testing. API 29 and API 36 startup, presentation, rotation, Activity recreation, and repeated native-window replacement remain explicit release-evidence gates rather than merge claims.